Network Support Library/RoseWare - Network Support Library.iso/btrieve/btr61m.exe/08CH4.TXT

Text File | 1993-07-16 | 18KB | 502 lines

CHAPTER 4    CONFIGURING AND USING THE REQUESTERS

Btrieve provides a DOS Requester, an OS/2
Requester, a Windows Requester, and a UnixWare
Requester.  This chapter provides configuration
options and instructions for loading and unloading the
Requester in each operating environment.

NOTE:  The Btrieve Requesters have changed (primarily
in key definition) between previous versions and
Btrieve v6.1.  Therefore, all workstations accessing
the Btrieve v6.1 NLM must use the Btrieve v6.1 Requesters.

For information about the new UnixWare Requester,
please refer to the Readme file that accompanies this
release.


DOS Requester

You must load the Btrieve DOS Requester (BREQUEST.EXE) at a
workstation running DOS before that workstation can access
network Btrieve files using the Btrieve NLM. The DOS
Requester loads into a DOS workstation's memory as a
Terminate and Stay Resident (TSR) program. You can access
local as well as remote files by running both client-based
(local) Btrieve and the Requester at your workstation.

NOTE: Client-based Btrieve is available only as part of the
Btrieve Developer's Kit and must be purchased separately.


DOS Requester Configuration Options

There are five configuration options for the Btrieve DOS
Requester:  NetWare Runtime Server Support (/C), Data
Message Length (/D), DOS Session Load (/L), Real-Time Data
Compression (/O), and Help (/?).  Previous versions of the
DOS Requester also supported the /S and /R options.  The
DOS Requester v6.x accepts the /S and /R options for
backwards compatibility, but otherwise ignores them.


NetWare Runtime Server Support (/C)

Range: None
Default: /C:1
Memory Required: Not applicable

This option allows you to enable or disable NetWare Runtime
server support.

/C:0 | /C:1 | /C:1,username,password

/C:0        Disables NetWare Runtime server support.
/C:         Enables NetWare Runtime server support.  Btrieve
            looks at the username for the drive (current
            server) on which you are presently running.

            If the username is SUPERVISOR, Btrieve searches
            for another username in the table of usernames
            for the servers onto which you are logged.

            If the username is not SUPERVISOR, Btrieve
            searches for that username on the NetWare
            Runtime server. If it is not a valid username,
            Btrieve returns an error at the time of the Open
            or Create request.

/C:1,username,password
            Enables NetWare Runtime server support. Btrieve
            verifies the specified username and password
            for the NetWare Runtime server. Btrieve returns
            an error if the specified username is not found
            or the password is invalid.

username
            Preferred login name on the NetWare
            Runtime server.  If you specify SUPERVISOR for
            the username, Btrieve returns an error and the
            DOS Requester will not load.

password
            Login password for the specified user.
            For information on using Btrieve with NetWare
            Runtime,  see Chapter 3, "Installing and
            Configuring Btrieve."


Data Message Length (/D)

Range: 532 through 57,000 bytes
Default: 4,096 bytes
Memory Required: 538 bytes + data message length

This option specifies the length of the largest record (or
the largest portion or chunk of a record) you want to
access through Btrieve.  (If you omit this option, the
Requester uses the default value, 8,192.) The Requester
uses this value to calculate the length of the data message
buffer reserved for passing records between Btrieve and
your applications.  The Requester maintains one copy of the
data message buffer.

The value you enter here should not exceed the largest
record size you configure for Btrieve through the Setup
utility since that is the maximum message that BSPXCOM can
receive.  (For more information, refer to the section
"Largest Record Size.") Specify the data message length in
bytes.  For example, if the largest record your application
uses is 3,000 bytes, specify the /D option as follows:

   /D:3000

Specifying a higher value than you need for the /D option
does not improve performance and may waste memory.


DOS Session Load (/L)

Range: Not applicable
Default: Not applicable
Memory Required: Not applicable

This option allows you to load another instance of BREQUEST
even if it is already loaded.  This option is useful if you
want to run Windows applications using the DOS Requester
while running DOS VM applications that are also using the
DOS Requester.

To run Windows applications that use the
DOS Requester, you must load BREQUEST before starting
Windows.  In order to run DOS applications in Windows, you
must load BREQUEST in each DOS session.  However, if you
load BREQUEST outside of Windows, you cannot load it again
in a DOS session.

For Windows applications using the DOS Requester, load
BREQUEST outside of Windows.  In each Windows DOS session
that will be running a Btrieve application, load BREQUEST
with the /L option.  Doing so will load another instance of
BREQUEST that is available only to the DOS session.

This operation provides the DOS session with its own copy of
BREQUEST and prevents the DOS session from using the
instance of BREQUEST that you loaded before starting
Windows.


Real-Time Data Compression (/O)

Range: None
Default: No compression
Memory Required: Approximately 32 KB on the workstation and 32
   KB per client on the server

In many cases (such as when implementing extended reads,
VATs), this option can help reduce network traffic by
reducing the number of packets required to complete a
request to Btrieve.  This option may, however, adversely
affect memory and performance.

Compressing and
decompressing data takes extra CPU time on both the server
and client sides.  Because of overhead, you should not use
this option with fast networks or with slow workstations
for clients.


Help (/?)

The /?  option lists the other options that are available
(/C, /D, and /O) and mentions that although the /S and /R
options are accepted for backwards compatibility, Btrieve
v6.x ignores them.  Loading the DOS Requester Load the DOS
Requester at the workstation by entering the following
command:

   [path] BREQUEST [option]

  path
  The pathname to the directory where the DOS Requester is
  stored.  You can omit the pathname if the DOS Requester is
  stored on the default drive or if it is located in a
  directory in your search path.

  option
  Any of the configuration options (/C, /D, /L, /O, or /?).
  For example, if the Requester is on the default drive and
  you want to specify a 2,048-byte data message length, enter
  BREQUEST /D:2048.

  The forward slash (/ ) before the configuration option is
  the only valid character you can use.  If you specify a
  dash (-) or a backslash ( \), the Requester may load
  improperly.


Unloading the DOS Requester

To unload the DOS Requester, use the DOS Requester utility,
BREQUTIL.EXE.  At the workstation where the DOS Requester is
loaded, enter BREQUTIL -STOP.  (To determine the version of
your DOS Requester, you can enter BREQUTIL -VER.)

NOTE:  If files have been left open (as happens, for
example, when an application does not issue a Close
operation for each open file), simply logging out of one or
more servers from a workstation does not close Btrieve
files or terminate the Btrieve SPX connection to the
server.  To close Btrieve files and terminate the
connection, use the BREQUTIL -STOP command.


OS/2 Requester

The following files must be loaded in a directory listed in
an OS/2 workstation╒s LIBPATH before a Btrieve application
can access the Btrieve NLM from that workstation:

o BTRCALLS.DLL - the Btrieve dynamic link Requester for OS/2
  workstations.

o NDBCOMM.DLL - the communications Requester for OS/2
  workstations.  NDBCOMM.DLL provides the necessary data
  communications between the workstation and the Btrieve
  NLM.

You can access local as well as remote files by running both
client-based (local) Btrieve and the Requester at your
workstation.  If you want to run both client-based Btrieve
and the Requester, you must use the OS/2 Conversion utility
(NDBCNVT.EXE) to convert the client-based BTRCALLS.DLL to
BTRLOCL.DLL.  (By default, the Requester and client-based
Btrieve have the same name.)

NOTE:  Client-based Btrieve is available only as part of the
Btrieve Developer╒s Kit and must be purchased separately.


OS/2 Requester Configuration Options

You are not required to specify any configuration options
for the OS/2 Requester.  Since the internal tables that
control the options are not fixed, the tables will grow as
needed.

There are three configuration options for the OS/2
Requester:  NetWare Runtime Server Support (/C), Data
Message Length (/D), and Number of Servers (/S).

NOTE: Although you can set the initial size of the tables using
the Data Message Length (/D) and the Number of Servers (/S)
options, setting table sizes is not recommended.


NetWare Runtime Server Support (/C)

Range: None
Default: /C:1
Memory Required: Not applicable

This option allows you to enable or disable NetWare Runtime
server support.

  /C:0 | /C:1 | /C:1,username,password

  /C:0        Disables NetWare Runtime server support.
  /C:1        Enables NetWare Runtime server support. Btrieve
        looks at the username for the drive (current
        server) on which you are presently running.
        If the username is SUPERVISOR, Btrieve searches
        for another username in the table of usernames
        for the servers onto which you are logged.

        If the username is not SUPERVISOR, Btrieve
        searches for that username on the NetWare
        Runtime server. If it is not a valid username,
        Btrieve returns an error at the time of the Open
        or Create request.

  /C:1,username,password
        Enables NetWare Runtime server support. Btrieve
        verifies the specified username and password for
        the NetWare Runtime server. Btrieve returns an
        error if the specified username is not found or
        the password is invalid.

  username Preferred login name on the NetWare Runtime server.
       If you specify SUPERVISOR for the username, Btrieve
       returns an error and the OS/2 Requester will not
       load.

  password Login password for the specified user.
       For information on using Btrieve with NetWare
       Runtime, see Chapter 3, "Installing and Configuring
       Btrieve."


Data Message Length (/D)

Range: 532 through 65,000 bytes
Default: 4,096 bytes
Memory Required: 538 bytes + data message length

The /D option specifies the length of the largest record
(or the largest portion or chunk of a record) you want to
access through Btrieve.  The OS/2 Requester uses this value
to calculate the length of the data message buffer reserved
for passing records between Btrieve and your applications.
The Requester maintains one copy of the data message buffer.

The value you enter here should not exceed the value you
specified for the Largest Record Size configuration option
in the Setup utility.  (For more information, refer to the
section "Largest Record Size.") The value for this option
represents the maximum message length that BSPXCOM can
receive.

Specify the record length in bytes.  For example, if the
largest record your application uses is 3,000 bytes,
specify the /D option as follows:

   /D:3000

Specifying a higher value than you need for the /D option
does not improve performance.


Number of Servers (/S)

Range: 1 through 255
Default: 8
Memory Required: 27 bytes per server

The /S option specifies the number of servers that have the
Btrieve NLM active on the network.


Configuring the OS/2 Requester

Set the Requester configuration options using the following
command:

   SET BRQPARMS=option

   option
   Any of the three configuration options (/C, /D, or /S).  Do
   not include a space between BRQPARMS and the equal sign.
   You can, however, insert a space between each configuration
   option you specify.

For example, to specify a 10,240-byte data message length
and four servers, issue the following command:

   SET BRQPARMS=/D:10240 /S:4

The forward slash (/ ) before the configuration option is
the only valid character you can use.  If you specify a
dash (-) or a backslash ( \), the Requester may load
improperly.


Loading the OS/2 Requester

An application may load the Btrieve for OS/2 Requester in
one of the following two ways:

o Implicitly - Your application can implicitly load the
  OS/2 Requester either by linking with the import library
  BTRCALLS.LIB or by specifying imported functions in the
  application definition file.  In either case, the
  operating system loads the OS/2 Requester automatically
  when the application is started.

o Explicitly - Your application can load the OS/2 Requester
  explicitly using the operating system API functions.  When
  the application loads the Requester explicitly, the
  operating system does not load the OS/2 Requester until
  notified to do so.


Unloading the OS/2 Requester

At an OS/2 workstation, the operating system removes the
dynamic link routines from memory when the application
terminates or when the application explicitly unloads the
OS/2 Requester using the operating system API.

NOTE:  If files have been left open (as happens, for
example, when an application does not issue a Close
operation for each open file), simply logging out of one or
more servers from a workstation does not close Btrieve
files or terminate the Btrieve SPX connection to the
server.  To close files and terminate the connection, you
must either unload the Requester or restart the
workstation.


Windows Requester

In the Windows environment, you must load the DOS
Requester, BREQUEST.EXE, before starting Windows.
Windows-based Btrieve applications access the Requester by
means of a DLL, WBTRCALL.DLL, which uses the DOS Protected
Mode Interface (DPMI) that Windows provides.

The Windows Requester (that is, WBTRCALL.DLL) is the
Btrieve interface DLL for Windows v3.x.  The DLL provides
the same API as client-based Btrieve and requires no
modification to the application.

You can access local as well as remote files by running both
client-based (local) Btrieve and the Requester at your
workstation. If you want to run both client-based Btrieve
and the Requester, you must run the Windows Conversion
utility (WNDBCNVT.EXE) to convert the client-based
WBTRCALL.DLL to WBTRLOCL.DLL.

NOTE: Client-based Btrieve must be purchased
separately.


Windows Requester Configuration Options

The following list describes the available configuration
options for the Windows Requester.  These options should be
specified in the NOVDB.INI file under [brequestDPMI].

NOVDB.INI is the Novell initialization file for the Windows
Requester.  It is included on the distribution diskette.

  Tasks=#      Specifies how many concurrent tasks may use
          the Windows Requester.  The range is 1
          through 255.    The default value is 10.

  Local=Yes/No      Instructs the Windows Requester to use
          client-based Btrieve for accessing files
          locally.  The default value is No.

  Chkparms=Yes/No Instructs the Windows Requester to validate
          pointers passed to it.  You should use this
          option only during development.  The default
          is No.


Loading the Windows Requester

The DOS Requester must be loaded in the DOS environment
before you start Windows.  To load the DOS Requester, use
the WINSTART.BAT file or type BREQUEST at the DOS prompt
before loading Windows.  An application may load the
Windows Requester in one of the following two ways:

o Implicitly - Your application can implicitly load the
  Windows Requester by either linking with the import
  library WBTRCALLS.LIB or by specifying imported functions
  in the application definition file.  When an application
  loads a DLL implicitly, the operating system automatically
  loads the DLL when the application is started.

o Explicitly - Your application may load the Windows
  Requester explicitly using the operating system API
  functions.  The operating system does not load the DLL
  until notified to do so.

NOTE:  If you want to run a DOS Btrieve application in the
DOS box and a Windows Btrieve application at the same time,
you must have the DOS Requester loaded in each DOS
session.  However, if you have already loaded the DOS
Requester before loading Windows, you cannot load the DOS
Requester in any subsequent DOS session.  Consequently, you
cannot run the DOS Btrieve application in the DOS box.

For Windows applications using the DOS Requester, load
BREQUEST outside of Windows.  In each Windows DOS session
that will be running a Btrieve application, load BREQUEST
with the /L option.  Doing so will load another instance of
BREQUEST that is available only to the DOS session.  This
operation provides the DOS session with its own copy of
BREQUEST and prevents the DOS session from using the
instance of BREQUEST that you loaded before starting
Windows.


Unloading the Windows Requester

At a Windows workstation, the operating system removes the
dynamic link routines from memory when the application
terminates or when the application explicitly unloads the
DLLs using the operating system API functions.

NOTE: If Btrieve files are left open in an application because
the application did not issue a Close operation, simply
logging out of one or more servers from a workstation does
not close the files or terminate the Btrieve SPX connection
to the server.  The files remain open until you restart the
workstation or unload the DOS Requester using BREQUTIL
-STOP.  Also, keep in mind that a Reset operation closes
files but does not unload the DOS Requester.